1.1 Critères d’acceptation

Afin d’assurer la cohérence de la collection et une certaine qualité du contenu des fiches Rzine, plusieurs critères d’acceptation ont été établis. Certains de ces critères sont soumis à un ou plusieurs évaluateur·rice·s, d’autres peuvent faire l’objet d’un refus immédiat de la part des éditeur·rice·s du comité de lecture.

Les éditeur·rice·s et les évaluateur·rice·s veilleront à ce que la démonstration soit contextualisée (champ disciplinaire d’application, enjeux en terme de reproductibilité…) et rigoureuse. Le code présenté se doit d’être lisible, commenté et reproductible. Les packages mobilisés doivent être brièvement décrits et leur utilisation justifiée. Enfin, les données utilisées dans le cadre de la démonstration doivent obligatoirement être sourcées, libres de droit et mises à disposition.

*Le cas échéant, le comité de lecture se réserve la possibilité de mettre en relation différents contributeur.rice.s pour leur proposer la rédaction collaborative d’une fiche.

1.2 Format et template

Une fiche Rzine est document computationnel, alternant du texte et du code (programmation lettrée). Il s’agit d’un fichier HTML produit en R Markdown. Il se construit avec R et repose sur les packages rmarkdown et knitr.

Le modèle de mise en page est mis à disposition via le package rzine. Son installation ainsi que la création d’une fiche Rzine vierge sont expliqués dans la partie 2.

1.3 Soumission et évaluation

L’ensemble du processus de soumission et d’évaluation d’une fiche se déroule sur GitHub. Cela facilite la gestion de version, permet l’archivage et la transparence de l’évaluation d’une fiche.

Pour être soumise à évaluation, une fiche doit être déposée et déployée sur GitHub (cf. partie 5).

Dans le cas où l’ensemble des critères d’acceptations sont respectés, le comité de lecture désigne un éditeur.rice référent qui coordonnera tout le processus d’évaluation et de publication. Il propose également deux évaluateur·rice·s à l’auteur·e. Une fois le processus d’évaluation enclenché, les retours (publics) des évaluateur·rice·s et de l’éditeur·rice se font directement sur GitHub (cf. partie 6).

1.4 Publication et licence d’utilisation

Une fois le processus d’évaluation terminée, les éditeur·rice·s du comité de lecture s’occupent de la mise en page finale de la fiche, du dépôt d’un DOI, du référencement du document sur HAL et de sa mise en ligne sur le site rzine.fr.

Le projet Rzine souhaite promouvoir les pratiques contribuant à une science plus ouverte et reproductible. C’est pour cette raison que l’ensemble des publications de la collection Rzine, ainsi que leurs codes sources, sont automatiquement mis à disposition de tou·te·s et libres de droit.

2.1 Installation du package rzine

Le package est mis à disposition sur un depôt de l’organisation Rzine sur l’instance GitLab de la TGIR Huma-num. Pour l’installer et le charger, exécutez les lignes suivantes :

# install.packages(remotes)
remotes::install_gitlab("rzine/package", host = "https://gitlab.huma-num.fr/", force = TRUE)
library(rzine)

2.2 Utiliser le template readrzine

Avant de générer une fiche Rzine vierge, il est important de spécifier un répertoire de travail. Pour cela, deux solutions s’offrent à vous :

1- La solution standart

Créez un répertoire sur votre ordinateur, et spécifiez-le comme répertoire de travail avec la fonction setwd(), exemple :

setwd("/home/jeanne/Documents/Fiche_rzine")

2- La solution Rstudio (recommandée)

Créez un projet Rstudio. Pour cela, cliquez sur File/New Project, sélectionnez New Directory, puis New Project :

rmarkdown::draft(file = "index.Rmd", 
                 template = "readrzine", 
                 package = "rzine", 
                 create_dir = FALSE, 
                 edit = FALSE)

2.3 Kniter la fiche (.html)

Le fichier le plus important est index.Rmd. Il s’agit du fichier R Markdown source à partir duquel sera généré la fiche Rzine en format HTML. Ne modifiez pas son nom.

Pour générer le document en format HTML, il suffit de kniter (tricoter) ce fichier. Cela revient à le convertir dans un premier temps en format markdown puis (dans ce cas) en format HTML via Pandoc (logiciel libre de conversion de documents).

Vous pouvez kniter (générer) le R Markdown readrzine en format HMTL de différente manière :

1- En ligne de code

Copiez-collez ces lignes de commande puis exécutez pour générer le fichier HTML :

rmarkdown::render("index.Rmd", envir = new.env())

2- En clic- bouton avec Rstudio

Ou cliquez tout simplement sur knit depuis l’interface Rstudio :

3- Raccourci clavier

Vous pouvez également utiliser le raccourci clavier suivant : CTRL+SHIFT+K

Cela engendre la création d’un fichier du même nom mais en format HTML (index.html) à la racine de votre répertoire. Il s’agit du fichier index.Rmd mis en page à partir du modèle readrzine.

Voici à quoi ressemble une fiche Rzine vierge knité :

3.1 L’en-tête

L’en-tête d’un document R Markdown (parfois appelé YAML header) est délimité par deux lignes de trois tirets et contient des métadonnées et les éléments de style du document. Voici à quoi ressemble l’en-tête vierge du template readrzine :

---
title: "Titre fiche"
subtitle: "Sous-titre fiche"
date: "`r Sys.Date()`"
author: 
 - name: Premier Auteur.e
   affiliation: Affiliation_1, Affiliation_2
 - name: Second Auteur.e
   affiliation: Affiliation_1, Affiliation_2
image: "featured.png"   
logo: "figures/rzine.png"  
output:
  rzine::readrzine:
    highlight: kate
    number_sections: true
csl: Rzine_citation.csl
bibliography: biblio.bib
nocite: |
  @*
link-citations: true
# github: "author/repository"
# gitlab: "gitlab.huma-num.fr/author/repository"
# doi: "xx.xxx/xxxx.xxxxxxx"
# licence: "by-sa"

# Only Creative Commons Licence 
# 5 possible choices : "by-nd", "by", "by-nc-sa", "by-nc","by-sa"
---

3.2 Le texte balisé en markdown

Le corps d’un document R Markdown comprend deux types de contenu, que l’on peut librement alterner :

• Des blocs de texte brut mis en forme selon la syntaxe markdown;
  
• Des blocs de code, appelés chunks (cf partie 3.3).

Le corps du document est constitué de texte mis en forme à l’aide de la syntaxe Markdown. Le markdown est un langage de balisage léger et très facile à maîtriser, qui permet de définir des niveaux de titres ou de mettre en forme le texte.

Par exemple, le texte suivant :

Ceci est du texte en *italique*, **gras** ou en ***gras italique***.

Pour définir des listes à puces, utilisez les **tirets** :

- premier élément
- second élément

Vous pouvez également ajouter des [liens cliquables](https://rzine.fr/) 

Se formalisera de la manière suivante dans le fichier HTML généré :

Ceci est du texte en italique, gras ou en Gras italique.

Pour définir des listes à puces, utilisez les tirets :

• premier élément
• deuxième élément

Ou encore ajouter des liens cliquables.

3.3 Les chunks

En plus du texte libre balisé en markdown, un document R Markdown peut évidemment contenir du code R.
Celui-ci doit être inclus dans des chunks délimités par la syntaxe suivante :

```{r}

x <- 37 + 12
print(x)

```

Pour insérer facilement un nouveau chunk, vous pouvez utiliser le menu Insert proposé par l’IDE RStudio, situé en haut à droite de l’éditeur de texte (à gauche du bouton Run) :

Vous pouvez également utiliser le raccourci clavier Ctrl+Alt+i pour générer un chunk vide.

Il est possible donner un nom (unique) à chaque chunk, de la façon suivante :

```{r nom_du_chunck}

```

Il n’est pas obligatoire de nommer un chunk, mais cela peut être utile pour localiser une erreur lors de la compilation du code.

Un certain nombre d’options peuvent également être ajoutées sous la forme option = valeur. Exemple :

```{r nom_du_chunck, echo = FALSE, warning = FALSE}

x <- 37 + 12
print(x)

```

L’option echo permet d’afficher, ou non, le code dans le document généré. L’option warning permet d’afficher ou non les warnings générés par le code en sortie. Voici la liste des principales options disponibles :

L’ensemble des options disponibles sont décrites dans le guide de référence R Markdown, et également dans plusieurs références listées ci-dessous.

3.4 Documentation de référence

Pour en savoir plus et se former au R Markdown et à la syntaxe markdown :

• Cookbook R Markdown, de Y. Xie, C. Dervieux & E. Riederer
• R Markdown Definitive Guide, de Y. Xie, J. J. Allaire & G. Grolemund
• R Markdown for Scientists, de Nicholas Tierney
• Introduction à R et au tidyverse, de Julien Barnier
• Travail collaboratif avec R, de Lino Galiana
• Pimp my RMD: a few tips for R Markdown, de Yan Holtz
• R for Data Science, de H. Wickham & G. Groelemund
• Guide de la syntaxe R Markdown, de Rstudio
• guide de référence R Markdown, de Rstudio
• R Markdown Cheatsheet, de Rstudio
• Writing Reproducible Research Papers with R Markdown, de Resul Umit

4.1 Métadonnées d’une fiche

Commencez par personnaliser l’en-tête du template readrzine (YAML header), en modifiant le titre, le sous-titre, le.s nom.s de ou des auteur.es et les affiliations, exemple :

---
title: "Analyse textuelle exploratoire"
subtitle: "Exploration d'un corpus de lettre avec les package Quanteda"
date: "`r Sys.Date()`"
author: 
 - name: Jeanne Dupont
   affiliation: UMR TEXTO, CNRS
 - name: Second Paul Edouard
   affiliation: Centre documentaire ED, Université de France

4.2 Contextualisation du contenu

Une fiche doit obligatoirement contenir une introduction, qui explicite l’objectif, le contenu et les données utilisés. Si nécessaire, il est également demandé au auteure.s de contextualiser le contenu, autant sur le plan thématique que technique. N’hésitez-pas à ajouter des références dans la bibliographie.

Une fiche Rzine doit s’adresser à l’ensemble des disciplines de SHS et des sciences territoriales. Considérez que vos lecteur.rice.s ne seront pas forcément des spécialistes de la thématique ou méthode présentée !

4.3 Données utilisées

L’intégralité des données utilisées pour une fiche doivent :

• Être présentées et décrites dans la fiche.
  
• Être libre d’utilisation et de diffusion.
  
• Être mises à disposition des lecteur.rice.s, même si ces données sont déjà en libre accès.
  
• Être associées à des métadonnées qui permettent de retracer et comprendre ces données.
  
• Respecter le Règlement Général sur la Protection des Données.

Toutes les données chargées et utilisées dans une fiche devront être stockées dans le répertoire :

Chaque fichier de données ajouté doit être associé à un fichier de métadonnées !

4.4 Packages utilisés

4.5 Image d’illustration et figures

```{r, echo=FALSE, fig.align='center', out.width = "15%"}

include_graphics("figures/folder_figures.png")

```

4.6 Formules mathématiques

Il est possible d’écrire des formules mathématiques en langage \(\TeX\). Pour cela, il suffit de délimiter le contenu \(\LaTeX\) par un ou deux symboles $, ex :

$$ y = \sqrt{\frac{1}{x + \beta}} $$ 

En mode Inline (un seul $) , les formules sont incluses à l’intérieur du paragraphe courant, ex : \(\sum_{i=1}^n X_i\)
En mode Displayed (deux $), elles apparaissent centrées et mises en exergue, ex : \[ y = \sqrt{\frac{1}{x + \beta}} \]

Sur le Web, vous trouverez beaucoup de documentation sur le langage de balisage markdown. Quelques références sont listées dans la partie 3.4

4.7 Ecriture de code R

4.8 Message d’alerte

https://getbootstrap.com/docs/4.0/components/alerts/

4.9 Références bibliographiques

Bien qu’il ne s’agisse pas d’une obligation, le template readrzine intègre automatiquement cette section. Si vous ne souhaitez pas afficher de bibliographie dans votre fiche, vous pouvez supprimer les lignes suivantes de votre R Markdown :

# Bibliographie {-}

<div id="refs"></div>

Si cette section vous intéresse, ne modifiez pas ces lignes. Il vous suffira de modifier/compléter les différentes références bibliographiques que vous souhaitez utiliser dans le fichier “biblio.bib” (format BibTeX), situé à la racine du répertoire :

Le template par défaut du fichier biblio.bib :

@Manual{R-base,
  title = {R: A Language and Environment for Statistical Computing},
  author = {{R Core Team}},
  organization = {R Foundation for Statistical Computing},
  address = {Vienna, Austria},
  year = {2020},
  url = {https://www.R-project.org/},
}

@Manual{R-knitr,
  title = {knitr: A General-Purpose Package for Dynamic Report Generation in R},
  author = {Yihui Xie},
  year = {2020},
  note = {R package version 1.28},
  url = {https://CRAN.R-project.org/package=knitr},
}

@Manual{R-rmdformats,
  title = {rmdformats: HTML Output Formats and Templates for 'rmarkdown' Documents},
  author = {Julien Barnier},
  year = {2021},
  note = {R package version 1.0.2},
  url = {https://github.com/juba/rmdformats},
}

Pour citer une références dans le corps du texte, utilisez la syntaxe suivante : [@Citation Key].
Par exemple [@R-base] affichera (R Core Team 2020) dans le corps du document.

Toutes les références bibliographiques présentes dans le fichier biblio.bib seront automatiquement ajoutées dans la section “Bibliographie”.

4.10 Glossaire

Cette section n’est pas obligatoire, cependant vos lecteur.rices ne seront pas forcément issus de votre discipline ou ne maîtriseront peut-être pas la thématique et/ou méthode présentée. Pour que l’ensemble de la démonstration soit compréhensible par un public large, vous pouvez utiliser la section “glossaire” pour définir certains termes utilisés dans la fiche.

Pour cela, il suffit d’utiliser la syntaxe markdown suivante dans le corps du texte :

Blabla bla bla bla bla mot à définir^[__Mot à définir__: Définition du terme... ect]

Au knit du document en format HTML, un numéro est associé et affiché après le “mot à définir”. Et ce mot et sa définition seront ajoutés dans la section glossaire.

Exemple : Mot à définir¹

Un lien interactif est alors automatiquement crée entre le “mot” dans le corps du texte et sa définition dans la section “Glossaire”.

Si vous ne souhaitez pas utilisez de “Glossaire”, vous pouvez supprimer ces lignes du template readrzine :

## Glossaire {- #endnotes}

<script type="text/javascript">

$(document).ready(function() {
  $('.footnotes ol').appendTo('#endnotes');
  $('.footnotes').remove();
});

</script>

4.11 Fichier readme.md

4.12 Annexes obligatoires

## Infos session  {-}
  
```{r session_info, echo=FALSE}
kableExtra::kable_styling(knitr::kable(rzine::sessionRzine()[[1]], row.names = F))
kableExtra::kable_styling(knitr::kable(rzine::sessionRzine()[[2]], row.names = F))
```

## Citation {-}

```{r Citation, echo=FALSE}

rref <- bibentry(
   bibtype = "article",
   title = "Titre de la fiche",
   author = person("Auteur.e 1", "Auteur.e 2" ),
   journal = "Rzine.fr",
   publisher = "FR CIST",
   year = 2021,
   url = "https://...")

``` 

`r capture.output(print(rref))`

### BibTex : {-}

```{r generateBibTex, echo=FALSE}

writeLines(toBibtex(rref), "cite.bib")
toBibtex(rref)

``` 


<br/>

5.1 Premiers pas sur Github

Le logiciel de gestion de versions décentralisé à utiliser pour la soumission est le plus connu et le plus utilisé dans le monde : GitHub. La première chose à faire est donc de vous créer un compte.

5.2 Remplissage du dépôt

Vous pouvez désormais y ajouter le répertoire contenant tous les fichiers (et sous-répertoires) de votre Fiche.

Il existe plusieurs méthodes pour téléverser des fichiers sur GitHub (en ligne de commande ou en clic-bouton). Nous présentons ici la méthode clic-bouton depuis l’interface de GitHub.

Pour cela, cliquez sur “Add file”, puis sur “Upload files” :.

Faîtes glisser l’ensemble des fichiers et sous-répertoires de votre fiche dans le dépôt :

Ajoutez un commentaire et cliquez sur “Commit changes” :

Vous venez de réaliser votre premier “commit” (enregistrement des changements). L’ensemble des fichiers sont désormais stockés sur le dépôt :

Ce dépôt étant paramétré comme Public, tout le monde peut désormais consulter et récupérer ces fichiers.

5.3 Déploiement de la fiche

Les fichiers sont consultables à l’état brut, mais une manipulation supplémentaire va permettre de mettre en ligne votre fiche (format HTML). Votre fiche mise en page sera ainsi consultable par tout le monde sur le web, sans avoir à gérer un serveur ou un site web. C’est trais utile, et très facile à faire !

5.4 Contacter comité de lecture

Il ne vous reste plus qu’à contacter le comité de lecture Rzine pour soumettre votre fiche à évaluation. Pour cela, envoyez un courriel à contact@rzine.fr, en précisant l’adresse du dépôt qui héberge votre fiche.

Vous serez contacté par le comité de lecture dans les 15 jours suivants l’envoi de ce courriel.

7.1 Mise en page finale

7.2 Attribution d’un DOI

En cas de publication, un DOI (Digital Object Identifier) sera attribué à chaque fiche par le biais de l’Institut de l’information scientifique et technique du CNRS (INIST).

Le DOI (et le lien vers la page des métadonnées) sera ajouté sur le document par le comité éditorial :

7.3 Dépôt sur HAL

7.4 Mise en ligne de la fiche

Un fois le processus de publication terminé, la fiche sera accessible à tout le monde depuis son dépôt Git. Pour une meilleure visibilité, elle sera également référencée et mise en valeur sur le site rzine.fr :